home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 016a / 4date.zip / 4DATE.DOC < prev   
Text File  |  1991-10-31  |  8KB  |  215 lines
  1.  
  2.                                 4DATE
  3.  
  4.                                   by
  5.  
  6.                            Marshall Giguere
  7.  
  8.                            October 28, 1991
  9.  
  10.                     Last revised: October 31, 1991
  11.  
  12. 4DATE provides a somewhat useful set of date computation functions
  13. for 4DOS version 4.xx.
  14.  
  15. 4DATE encapsulates the complete set of supplied functions in one .BTM
  16. file.  I choose this as opposed to scattering things to the four
  17. corners of the world, it takes up less total disk space being in one
  18. file and doesn't take up alias space either.  In order to accomplish
  19. this 4DATE incorporates a primitive dispatching mechanism for
  20. selecting the called function.
  21.  
  22. 4DATE functions are broken into two categories: User, and Primitive.
  23. User functions display the values they return.  Primitive functions
  24. are just that, they perform a computation and return a result that is
  25. useful for either further computation, or display.
  26.  
  27.                  4DATE calling and return conventions
  28.  
  29. All 4DATE functions are enclosed within the file 4DATE.BTM.  Each
  30. function is called by passing its name and any arguments to 4DATE:
  31.  
  32.         4DATE function-name arg...
  33.  
  34. where function-name is the name of the function to perform and arg...
  35. is an optional list of argument values.
  36.  
  37. All 4DATE primitive functions return their values to the current
  38. environment in the named variable "_$".  This allows you to reuse the
  39. result of a 4DATE computation in another computation or whatever your
  40. little heart desires.  As an example the 4DATE function CJUL returns
  41. the "Julian" day for a specified year in the variable "_$".
  42.  
  43.         4DATE CJUL %_DATE^ECHO %_$
  44.  
  45. Typing the above command will display the "Julian" date for the
  46. currently set system date.  It should be further noted that ALL USER
  47. functions call a Primitive function to do their task.  This has the
  48. desirable side-effect of also returning the displayed value in the
  49. return variable "%_$".
  50.  
  51.                       4DATE Available Functions
  52.  
  53. 4DATE provides the following functions:
  54.  
  55.     CJUL - 4DATE CJUL date (Primitive function)
  56.            Return the "Julian" day of year for the specified date.
  57.  
  58.     DDATE - 4DATE DDATE integer [aDate] (Primitive function)
  59.             DeltaDate returns the actual date for a given
  60.             number of days before or after a given date.
  61.  
  62.     DIFF - 4DATE DIFF date1 date2 (Primitive function)
  63.            Compute the absolute difference between two dates.
  64.  
  65.     DJD - 4DATE DJD julianDate [year] (User level function)
  66.           Display Julian date as calendar Date.  If no year is
  67.           specified the current year is assumed.
  68.  
  69.     DSTRUCT - 4DATE DSTRUCT date dv1 dv2 dv3 (Primitive function)
  70.               Takes a date and returns with the given environment
  71.               variables set to date values.
  72.  
  73.     DOW -   4DATE DOW [date [century]] (Primitive function)
  74.             Uses Zellers congruence to compute the day-of-the-week.
  75.             U.S. date format assumed (see function for changing this).
  76.  
  77.     FDOW - Fast Day-Of-Week (Primitive function)
  78.            CAUTION - this function may leave system date
  79.            in an incorrect state if interrupted.
  80.  
  81.     HELP - Displays this page.
  82.  
  83.     IS - 4DATE IS integer (User level function)
  84.          Displays the date for the given number of
  85.          days into the past or future from today.
  86.  
  87.     J2D - 4DATE J2D julianDate [year] (Primitive function)
  88.           Converts a Julian day to a calendar date.
  89.           The current year is the default.
  90.  
  91.     JDAY - 4DATE JDAY (User level function)
  92.            Displays todays "Julian" day of the year.
  93.  
  94. The choice of names is I admit somewhat idiosyncratic but coming up
  95. with names is an idiosyncratic process at best.
  96.  
  97. It is arguable as to the "real" need for the existence of User level
  98. functions at all, however, I found myself doing those operations so
  99. often the long way that it seemed reasonable to add them as user
  100. functions.  It is of course entirely possible to add the same
  101. functionality via a set of aliases.  As an example JDAY could have
  102. been implemented with the following alias: 
  103.  
  104.         JDAY=`4DATE CJUL %_date^ECHO Julian date: %_$`
  105.  
  106.                           Efficiency & 4DATE
  107.  
  108. It is provably true that the above alias would be faster than the
  109. current method of invoking another copy of 4DATE.  The recursive call
  110. costs roughly double the time of the above alias not to mention the
  111. memory cost of loading two copies of the .BTM into memory.  The
  112. disadvantages of the alias approach are primarily: containing the
  113. implementation in one space, and loss of alias space.  You can in
  114. fact create the above alias and get the speed without conflicting
  115. with, or changing the implementation package, again at the cost of
  116. using alias space.
  117.  
  118. What we are dealing here is the classic devils choice, do I want
  119. speed, or space and where?  My reason for avoiding the use of aliases
  120. is primarily to accomplish my goal of a single implementation space
  121. and to keep the use of disk real estate efficient.  My DOS system
  122. allocates files using 2048 byte clusters.  My current 4DATE spans 4
  123. clusters, had I opted for each function in a separate file 11
  124. clusters minimum would have been allocated for a total of 22,528 vs.
  125. 8,192.  What can I say MS-DOS has a miserable mechanism for managing
  126. the large number of relatively small files that tend to accumulate on
  127. typical system.  It should also be noted that some of the 4DATE
  128. functions cannot be implemented as aliases due to their length.
  129.  
  130. What it all boils down to is that efficiency is what you perceive it
  131. to be for a given context.  There is no absolute efficiency, just as
  132. there is no absolute time.  Efficiency depends on what your goals and
  133. constraints make it.  Fast implementations tend to be inefficient in
  134. their use of space, compact implementations tend to be iteratively
  135. slow.  My choices were based on my analysis that alias space is more
  136. limited than transient program space and 4DATE is fast enough for all
  137. practical purposes that loading a second copy of 4DATE would only be
  138. detectable on a slow machine (disk caching helps tremendously).
  139.  
  140.  
  141.                                EXAMPLES
  142.                                --------
  143. Show the day-of-the-week for today*:
  144.  
  145. C:\BIN >4DATE DOW^ECHO %_$
  146. Mon
  147.  
  148. C:\BIN >
  149.  
  150. ---------------
  151.  
  152. Show the day-of-the-week for Jan. 1, 1991:
  153.  
  154. C:\BIN >4DATE DOW 01-01-91^ECHO %_$
  155. Tue
  156.  
  157. C:\BIN >
  158. ---------------
  159.  
  160. Show the Julian date for today*:
  161.  
  162. C:\BIN >4DATE JDAY
  163. Julian date: 301
  164.  
  165. C:\BIN >
  166.  
  167. ---------------
  168.  
  169. Display the date for the day 5 days from today*:
  170.  
  171. C:\BIN >4DATE IS 5
  172. Date is: 11-02-91
  173.  
  174. C:\BIN >
  175.  
  176. ---------------
  177.  
  178. Display the date for the day 5 days before today*:
  179.  
  180. C:\BIN >4DATE IS -5
  181. Date is: 10-23-91
  182.  
  183. C:\BIN >
  184.  
  185. ----------------
  186.  
  187. *note: today = 10-28-91
  188.  
  189.  
  190.                               Conclusion
  191.                               ----------
  192.  
  193. One might certainly ask why do this at all?  And I could say why not,
  194. but that begs the question.  There are a large number of tasks in the
  195. arena of system administration that can only be accomplished with the
  196. ability to do some kind of date computation and manipulation, not to
  197. mention the simple problem of managing your own time schedule and DOS
  198. in general lacks any useful date manipulation features.  Also I gotta
  199. say it was just plain fun seeing how much I could squeeze out of 4DOS
  200. (take a look at the implementation of Zeller's congruence).
  201.  
  202.                            Acknowledgements
  203.                            ----------------
  204.  
  205. The implementation of Zeller's Congruence is based on the one
  206. published by Jeff Duntemann in the October 1990 issue of Dr. Dobb's
  207. Journal. 
  208.  
  209. Rex Conn for implementing my suggestion on indirect addressing for
  210. environment variables in 4DOS, without which Zeller's Congruence would
  211. have been a lot more difficult, thanks Rex.
  212.  
  213. J.P. Software in general for creating 4DOS and listening to my
  214. endless enhancement requests and providing help and suggestions.
  215.